Claude Code 구축을 통해 얻은 교훈: 우리는 Skills를 어떻게 활용하는가
![](data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48"><rect fill-opacity="0"/></svg>)
Skills는 Claude Code에서 가장 많이 사용되는 확장 포인트 중 하나가 되었습니다. 유연하고, 만들기 쉬우며, 배포도 간단합니다.
하지만 이러한 유연성 때문에 무엇이 가장 잘 작동하는지 파악하기 어렵기도 합니다. 어떤 종류의 skill이 만들 만한 가치가 있을까요? 좋은 skill을 작성하는 비결은 무엇일까요? 언제 다른 사람들과 공유해야 할까요?
Anthropic에서는 Claude Code의 skills를 광범위하게 활용하고 있으며, 수백 개가 현재 활발히 사용되고 있습니다. 이 글은 skills를 통해 개발을 가속화하면서 우리가 배운 교훈들입니다.
Skills란 무엇인가?
skills가 처음이시라면,최신 강의인를 시청해 보시길 권합니다. 이 글은 여러분이 skills에 어느 정도 익숙하다는 것을 전제로 합니다.
skills에 대해 흔히 듣는 오해 중 하나는 skills가 "단지 마크다운 파일"이라는 것인데요, skills의 가장 흥미로운 점은 단순한 텍스트 파일이 아니라는 점입니다. skills는 에이전트가 탐색하고, 열어보고, 조작할 수 있는 스크립트, 에셋, 데이터 등을 포함할 수 있는 폴더입니다.
Claude Code에서 가장 흥미로운 skills 중 일부는 이러한 설정 옵션과 폴더 구조를 창의적으로 활용한다는 것을 알게 되었습니다.
Skills의 유형
우리가 가진 모든 skills를 정리해 본 결과, 몇 가지 반복되는 카테고리로 분류된다는 것을 알았습니다. 좋은 skills는 하나의 카테고리에 깔끔하게 맞아 떨어지고, 모호한 skills는 여러 카테고리에 걸쳐 있습니다. 이것이 확정적인 목록은 아니지만, 조직 내에 빠진 skill이 없는지 점검해 볼 수 있는 좋은 관점이 됩니다.
1. 라이브러리 및 API 레퍼런스
라이브러리, CLI, SDK를 올바르게 사용하는 방법을 설명하는 skills입니다. 내부 라이브러리나 Claude Code가 가끔 어려워하는 일반 라이브러리 모두에 사용할 수 있습니다. 이러한 skills는 보통 참조 코드 스니펫 폴더와, Claude가 스크립트를 작성할 때 피해야 할 함정(gotcha) 목록을 포함합니다.
예시:
- billing-lib — 여러분의 내부 결제 라이브러리: 엣지 케이스, 실수하기 쉬운 지점 등
- internal-platform-cli — 내부 CLI 래퍼의 모든 서브커맨드와 언제 사용해야 하는지에 대한 예제
- frontend-design — Claude가 여러분의 디자인 시스템을 더 잘 다루도록 만들기
2. 제품 검증
코드가 제대로 동작하는지 테스트하거나 검증하는 방법을 설명하는 skills입니다. playwright, tmux 등 외부 도구와 함께 사용되어 검증 작업을 수행하는 경우가 많습니다.
검증용 skills는 Claude의 출력이 올바른지 확인하는 데 매우 유용합니다. 엔지니어 한 명이 한 주를 통째로 투자해 검증 skills를 훌륭하게 만드는 것도 가치 있는 일입니다.
Claude가 출력 결과를 비디오로 녹화하도록 해서 정확히 무엇을 테스트했는지 확인하거나, 각 단계에서 상태에 대한 프로그램적 단언(assertion)을 강제하는 기법을 고려해 보세요. 이러한 작업은 주로 skill에 다양한 스크립트를 포함시킴으로써 수행됩니다.
예시:
- signup-flow-driver — 헤드리스 브라우저에서 가입 → 이메일 인증 → 온보딩 플로우를 실행하며, 각 단계에서 상태를 단언할 수 있는 hook을 제공
- checkout-verifier — Stripe 테스트 카드로 체크아웃 UI를 구동하고, 인보이스가 실제로 올바른 상태로 도달하는지 검증
- tmux-cli-driver — TTY가 필요한 인터랙티브 CLI 테스트용
3. 데이터 조회 및 분석
데이터와 모니터링 스택에 연결되는 skills입니다. 자격 증명으로 데이터를 가져오는 라이브러리, 특정 대시보드 ID 등뿐만 아니라 일반적인 워크플로우나 데이터를 얻는 방법에 대한 설명도 포함할 수 있습니다.
예시:
- funnel-query — "가입 → 활성화 → 결제 전환을 보려면 어떤 이벤트를 조인해야 하나요"와 실제 표준 user_id가 있는 테이블
- cohort-compare — 두 코호트의 리텐션이나 전환율을 비교하고, 통계적으로 유의미한 차이를 표시하며, 세그먼트 정의로 링크 제공
- grafana — 데이터소스 UID, 클러스터 이름, 문제 → 대시보드 조회 테이블
4. 업무 프로세스 및 팀 자동화
반복적인 워크플로우를 하나의 명령으로 자동화하는 skills입니다. 이런 skills는 보통 상당히 간단한 지시사항을 담고 있지만, 다른 skills나 MCP에 대한 더 복잡한 의존성이 있을 수 있습니다. 이러한 skills의 경우, 이전 결과를 로그 파일에 저장하면 모델이 일관성을 유지하고 워크플로우의 이전 실행 내역을 되돌아보는 데 도움이 됩니다.
예시:
- standup-post — 티켓 트래커, GitHub 활동, 이전 Slack 내역을 집계해 변경사항만 담은 스탠드업 포맷으로 생성
- create-<ticket-system>-ticket — 스키마(유효한 enum 값, 필수 필드)를 강제하고 생성 후 워크플로우(리뷰어 호출, Slack에 링크 게시)까지 처리
- weekly-recap — 병합된 PR + 완료된 티켓 + 배포를 모아 주간 회고 포스트로 포맷팅
5. 코드 스캐폴딩 및 템플릿
코드베이스 내 특정 기능을 위한 프레임워크 보일러플레이트를 생성하는 skills입니다. 이러한 skills는 조합 가능한 스크립트와 결합해 사용할 수 있습니다. 특히 스캐폴딩에 코드만으로는 완전히 담을 수 없는 자연어 요구사항이 있을 때 유용합니다.
예시:
- new-<framework>-workflow — 여러분의 어노테이션으로 새로운 서비스/워크플로우/핸들러를 스캐폴딩
- new-migration — 마이그레이션 파일 템플릿과 일반적인 함정 모음
- create-app — 인증, 로깅, 배포 설정이 미리 연결된 신규 내부 앱 생성
6. 코드 품질 및 리뷰
조직 내 코드 품질을 강제하고 코드 리뷰를 돕는 skills입니다. 최대한의 견고함을 위해 결정론적 스크립트나 도구를 포함할 수 있습니다. 이러한 skills는 hooks의 일부로 또는 GitHub Action 안에서 자동으로 실행하도록 할 수도 있습니다.
- adversarial-review — 새로운 시각의 서브에이전트를 띄워 비판하게 하고, 수정사항을 구현하며, 지적사항이 사소한 것만 남을 때까지 반복
- code-style — 코드 스타일을 강제, 특히 Claude가 기본적으로 잘 다루지 못하는 스타일을 다룸
- testing-practices — 테스트 작성 방법 및 테스트 대상에 대한 지침
7. CI/CD 및 배포
코드베이스 내에서 코드를 가져오고, 푸시하고, 배포하는 데 도움을 주는 skills입니다. 이러한 skills는 데이터를 수집하기 위해 다른 skills를 참조할 수도 있습니다.
예시:
- babysit-pr — PR을 모니터링 → flaky한 CI 재시도 → 머지 충돌 해결 → 자동 머지 활성화
- deploy-<service> — 빌드 → 스모크 테스트 → 에러율 비교를 통한 점진적 트래픽 롤아웃 → 회귀 발생 시 자동 롤백
- cherry-pick-prod — 격리된 worktree → cherry-pick → 충돌 해결 → 템플릿 기반 PR 생성
8. Runbook
증상(예: Slack 스레드, 알림, 에러 시그니처)을 입력받아 여러 도구를 활용해 조사를 진행하고, 구조화된 보고서를 생성하는 skills입니다.
예시:
- <service>-debugging — 트래픽이 가장 많은 서비스들을 대상으로 증상 → 도구 → 쿼리 패턴을 매핑
- oncall-runner — 알림을 가져와 → 흔한 원인들을 점검 → 조사 결과를 포맷팅
- log-correlator — 요청 ID가 주어지면, 해당 요청을 거쳐갔을 만한 모든 시스템에서 일치하는 로그를 수집
9. 인프라 운영
일상적인 유지보수와 운영 절차를 수행하는 skills — 그중 일부는 가드레일의 도움이 필요한 파괴적 작업을 포함합니다. 이를 통해 엔지니어가 중요한 운영 작업에서 모범 사례를 따르기가 더 쉬워집니다.
예시:
- <resource>-orphans — 고아가 된 Pod/볼륨을 찾아내 → Slack에 게시 → 대기 기간 → 사용자 확인 → 연쇄 정리
- dependency-management — 조직의 의존성 승인 워크플로우
- cost-investigation — "우리 스토리지/egress 비용이 왜 급증했지"를 특정 버킷과 쿼리 패턴과 함께 조사
Skills를 만드는 팁
만들 skill을 결정했다면, 어떻게 작성해야 할까요? 다음은 우리가 찾아낸 모범 사례, 팁, 그리고 요령들입니다.
뻔한 내용은 적지 말기
Claude Code는 여러분의 코드베이스에 대해 많이 알고 있으며, Claude는 기본적인 여러 견해를 포함해 코딩에 대해 많이 알고 있습니다. 주로 지식을 전달하는 skill을 공개하는 경우, Claude가 평소의 사고방식에서 벗어나도록 유도하는 정보에 집중하세요.
좋은 예로이 있습니다 — Anthropic의 한 엔지니어가 고객들과 반복적으로 피드백을 주고받으며 Claude의 디자인 감각을 향상시키기 위해 만들었고, Inter 폰트나 보라색 그라데이션 같은 전형적인 패턴을 피하도록 했습니다.
Gotchas 섹션 구축하기
어떤 skill이든 가장 신호 대비 가치가 높은 내용은 Gotchas 섹션입니다. 이 섹션은 Claude가 해당 skill을 사용할 때 자주 부딪히는 실패 지점들을 바탕으로 축적해 나가야 합니다. 이상적으로는 시간이 지나면서 skill을 업데이트해 이러한 함정들을 지속적으로 반영해야 합니다.
파일 시스템과 점진적 공개(Progressive Disclosure) 활용하기
앞서 말했듯이, skill은 단순한 마크다운 파일이 아니라 폴더입니다. 파일 시스템 전체를 컨텍스트 엔지니어링과 점진적 공개의 한 형태로 생각해야 합니다. Claude에게 skill에 어떤 파일들이 있는지 알려주면, 적절한 시점에 해당 파일들을 읽어볼 것입니다.
점진적 공개의 가장 단순한 형태는 Claude가 참고할 다른 마크다운 파일을 가리키는 것입니다. 예를 들어, 자세한 함수 시그니처와 사용 예제를 references/api.md로 분리할 수 있습니다.
또 다른 예: 최종 출력물이 마크다운 파일이라면, 복사해서 사용할 수 있는 템플릿 파일을 assets/ 안에 포함시킬 수도 있습니다.
레퍼런스, 스크립트, 예제 등의 폴더를 구성할 수 있고, 이는 Claude가 더 효과적으로 작업하도록 돕습니다.
Claude를 한 길로 몰아가지 말기
Claude는 일반적으로 여러분의 지시사항을 충실히 따르려고 하는데, skills는 매우 재사용성이 높기 때문에 지시가 너무 구체적이 되지 않도록 주의해야 합니다. Claude에게 필요한 정보를 주되, 상황에 맞게 적응할 수 있는 유연성도 함께 제공하세요. 예를 들어:
셋업 과정을 미리 고민하기
어떤 skills는 사용자의 컨텍스트를 기반으로 셋업이 필요할 수 있습니다. 예를 들어, 스탠드업을 Slack에 게시하는 skill을 만든다면, Claude가 어느 Slack 채널에 올릴지 사용자에게 물어보도록 하고 싶을 것입니다.
이러한 목적에 적합한 패턴은 위 예시처럼 셋업 정보를 skill 디렉터리의 config.json 파일에 저장하는 것입니다. 설정이 되어 있지 않으면, 에이전트가 사용자에게 필요한 정보를 물어볼 수 있습니다.
에이전트가 구조화된 객관식 질문을 제시하기를 원한다면, Claude에게 AskUserQuestion 도구를 사용하도록 지시할 수 있습니다.
Description 필드는 모델을 위한 것
Claude Code는 세션을 시작할 때 사용 가능한 모든 skill과 그 설명으로 구성된 목록을 만듭니다. Claude는 이 목록을 훑어보며 "이 요청에 해당하는 skill이 있는가?"를 판단합니다. 즉, description 필드는 요약문이 아니라 — 이 skill을 언제 트리거해야 하는지에 대한 설명입니다.
메모리와 데이터 저장
일부 skills는 내부에 데이터를 저장하는 방식으로 일종의 메모리 기능을 포함할 수 있습니다. 데이터는 단순한 추가 전용 텍스트 로그 파일이나 JSON 파일, 혹은 SQLite 데이터베이스처럼 복잡한 형태로도 저장할 수 있습니다.
예를 들어, standup-post skill은 지금까지 작성한 모든 포스트를 standups.log에 기록해 둘 수 있습니다. 그러면 다음번에 실행할 때 Claude가 자신의 이력을 읽고 어제 이후로 무엇이 바뀌었는지 파악할 수 있습니다.
skill 디렉터리에 저장된 데이터는 skill을 업그레이드할 때 삭제될 수 있으므로, 안정적인 폴더에 저장해야 합니다. 현재는 플러그인별로 데이터를 저장할 수 있는 안정적인 폴더로 `${CLAUDE_PLUGIN_DATA}`을 제공합니다.
스크립트 저장 및 코드 생성
Claude에게 줄 수 있는 가장 강력한 도구 중 하나는 코드입니다. Claude에게 스크립트와 라이브러리를 제공하면, 보일러플레이트를 재구성하는 대신 무엇을 조합해 다음에 무엇을 할지 결정하는 데 턴을 쓸 수 있습니다.
예를 들어, 데이터 사이언스 skill에서는 이벤트 소스로부터 데이터를 가져오는 함수 라이브러리를 가지고 있을 수 있습니다. Claude가 복잡한 분석을 수행할 수 있도록 아래와 같이 헬퍼 함수 모음을 제공할 수 있습니다:
그러면 Claude는 "화요일에 무슨 일이 있었지?" 같은 프롬프트에 대해 이 기능들을 조합하는 스크립트를 즉석에서 생성해 더 심화된 분석을 수행할 수 있습니다.
주문형(On Demand) Hooks
skills는 해당 skill이 호출될 때만 활성화되고 세션이 지속되는 동안 유지되는 hooks를 포함할 수 있습니다. 항상 실행하고 싶지는 않지만 특정 상황에서는 매우 유용한, 좀 더 단정적인(opinionated) hooks에 이 방식을 사용하세요.
예를 들어:
- /careful— Bash의 PreToolUse matcher를 통해 rm -rf, DROP TABLE, force-push, kubectl delete 등을 차단. 프로덕션을 건드린다는 것을 알 때만 사용하고 싶을 것입니다 — 항상 켜져 있다면 미쳐버릴지도 모릅니다
- /freeze— 특정 디렉터리에 속하지 않은 Edit/Write를 모두 차단. 다음과 같은 경우에 유용
- 디버깅 시: "로그만 추가하고 싶은데 계속 관련 없는 부분을 '고쳐' 버리는 경우"
Skills 배포하기
Skills의 가장 큰 이점 중 하나는 팀의 나머지 구성원과 공유할 수 있다는 점입니다.
다른 사람들과 skills를 공유하는 방법은 두 가지가 있습니다:
- skills를 리포지토리에 커밋하기 (./.claude/skills 아래)
상대적으로 적은 수의 리포지토리에서 작업하는 작은 팀에게는 skills를 리포지토리에 커밋하는 방식이 잘 맞습니다. 하지만 커밋되는 모든 skill은 모델의 컨텍스트에도 조금씩 추가됩니다. 규모가 커지면 내부 플러그인 마켓플레이스를 통해 skills를 배포하고, 팀 구성원들이 어떤 것을 설치할지 선택하도록 할 수 있습니다.
마켓플레이스 관리하기
어떤 skills를 마켓플레이스에 올릴지 어떻게 결정할까요? 사람들은 어떻게 제출할까요?
이를 결정하는 중앙화된 팀은 없으며, 가장 유용한 skills를 유기적으로 찾아내려고 합니다. 사람들에게 시험해보게 하고 싶은 skill이 있다면, GitHub의 샌드박스 폴더에 업로드하고 Slack이나 다른 포럼에서 공유하면 됩니다.
skill이 어느 정도 인기를 얻으면(이는 skill 소유자가 판단합니다) 해당 skill을 마켓플레이스로 옮기는 PR을 올릴 수 있습니다.
한 가지 주의사항은, 좋지 않거나 중복되는 skills를 만들기는 꽤 쉽다는 점입니다. 따라서 공개 전에 어떤 형태로든 큐레이션 방법을 마련해두는 것이 중요합니다.
Skills 조합하기
서로 의존관계가 있는 skills를 만들고 싶을 수도 있습니다. 예를 들어, 파일을 업로드하는 file upload skill과, CSV를 생성한 뒤 업로드하는 CSV generation skill이 있을 수 있습니다. 이러한 종류의 의존성 관리는 아직 마켓플레이스나 skills에 기본적으로 내장되어 있지는 않지만, 다른 skill을 이름으로 참조하기만 해도 모델이 해당 skill이 설치되어 있다면 호출해 줍니다.
Skills 측정하기
skill이 잘 동작하는지 파악하기 위해, 우리는 사내에서 skill 사용 내역을 로깅할 수 있는 PreToolUse hook을 사용합니다 (). 이를 통해 인기 있는 skills나 기대에 비해 덜 트리거되는 skills를 찾을 수 있습니다.
결론
Skills는 에이전트를 위한 믿을 수 없을 만큼 강력하고 유연한 도구이지만, 아직 초기 단계이며 우리 모두가 skills를 가장 잘 활용하는 방법을 함께 알아가고 있는 중입니다.
이 글은 확정된 가이드라기보다는 실제로 효과가 있었던 유용한 팁 모음집에 가깝다고 생각해 주세요. skills를 이해하는 가장 좋은 방법은 일단 시작해 보고, 실험하고, 무엇이 자신에게 잘 맞는지 직접 확인해 보는 것입니다. 우리 skills 대부분도 몇 줄의 글과 하나의 함정(gotcha) 정리에서 시작했고, Claude가 새로운 엣지 케이스를 만날 때마다 사람들이 계속 내용을 추가하면서 점점 더 좋아졌습니다.
이 글이 도움이 되었기를 바라며, 궁금한 점이 있다면 알려주세요.
나만의 아티클을 게시하고 싶으신가요?
Premium 등급으로 업그레이드